<html>
<!--
  == This software is subject to the terms of the Eclipse Public License v1.0
  == Agreement, available at the following URL:
  == http://www.eclipse.org/legal/epl-v10.html.
  == You must accept the terms of that agreement to use this software.
  ==
  == Copyright (C) 2002-2005 Julian Hyde
  == Copyright (C) 2005-2006 Pentaho
  == All Rights Reserved.
  -->
<head>
    <link rel="stylesheet" type="text/css" href="stylesheet.css"/>
	<title>Pentaho Analysis Services: Mondrian Components</title>
</head>
<body>
<!-- doc2web start -->

<!-- page title -->
<div class="contentheading">Mondrian Components</div>
<!-- end page title -->

<!-- 
########################
##  Introduction   #####
######################## -->
<h3>Introduction</h3>

<p>See <a href="olap.html">OLAP</a> and <a
href="architecture.html">architecture</a>.</p>
<!-- 
########################
##  overview start #####
######################## -->
<h3>Components</h3>
<i>to be written...</i>
<!-- 
########################
##  Caching        #####
######################## -->
<h3>Caching<a name="caching">&nbsp;</a></h3>

<p>The various subsystems of mondrian have different memory requirements. Some
of them require a fixed amount of memory to do their work, whereas others can
exploit extra memory to increase their performance. This is an overview of how
the various subsystems use memory.</p>

<p><dfn>Caching</dfn> is a scheme whereby a
component uses extra memory when it is available in order to boost its
performance, and when times are hard, it releases memory with loss of
performance but with no loss of correctness. A cache&nbsp; is the use of extra
memory when times are good, use varying amounts of memory.</p>
<p><dfn>Garbage collection</dfn> is carried out by
the Java VM to reclaim objects which are unreachable from 'live' objects. A
special construct called a <i>soft reference</i> allows objects to be
garbage-collected in hard times.</p>
<p>The garbage collector is not very discriminating in what it chooses to throw
out, so mondrian has its own caching strategy. There are several caches in the
system (described below), but they all of the objects in these caches are
registered in the singleton instance of
<a href="api/mondrian/rolap/CachePool.html">
class mondrian.rolap.CachePool</a> (currently there is just a single instance).
The cache pool doesn't actually store the objects, but handles all of the events
related to their life cycle in a cache. It weighs objects' cost (some function
involving their size in bytes and their usefulness, which is based upon how
recently they were used) and their benefit (the effort it would take to
re-compute them).</p>

<p>The cache pool is not infallible &mdash; in particular, it can not adapt to  conditions where memory is in short supply &mdash; so uses
soft references, so that
the garbage collector can overrule its wisdom.</p>
<p>Cached objects must obey the following contract:</p>
<ol>
  <li>
  <p>They must implement
  <a href="api/mondrian/rolap/CachePool.Cacheable.html">
  interface mondrian.rolap.CachePool.Cacheable</a>, which includes methods to
  measure objects' cost, benefit, record each time they are used, and tell them
  to remove themselves from their cache.</li>

  <li>They must call
  <a href="api/mondrian/rolap/CachePool.html#register(Cacheable)">CachePool.register(Cacheable)</a>
  either in their constructor or, in any case, before they are made visible in
  their cache.</li>
  <li>They they must call
  <a href="api/mondrian/rolap/CachePool.html#registerDeath">
  CachePool.unregister(Cacheable)</a> when they are removed from their cache and
  in their <code>finalize()</code> method.</li>

  <li>They must be despensable: if they disappear, their subsystem will continue
  to work correctly, albeit slower. A subsystem can declare an object to be
  temporarily indispensable by calling
  <a href="api/mondrian/rolap/CachePool.html#pin(Cacheable,Collection)">CachePool.pin(Cacheable, Collection)</a> and then unpin it a short time later.</li>
  <li dir="ltr">
  <p dir="ltr">Their cache must reference them via soft references, so that they
  are available for garbage collection. </li>
  <li>Thread safety. Their cache must be thread-safe.</li>
</ol>
<p>If a cached object takes a significant time to initialize, it may not be
possible to construct it, register it, and initialize it within the same
synchronized section without unnacceptably reducing concurrency. If this is the
case, you should use phased construction. First construct and register the
object, but mark it 'under construction'. Then release the lock on the CachePool
and the object's cache, and continue initializing the object. Other threads will
be able to see the object, and should be able to wait until the object is
constructed. The method
<a href="api/mondrian/rolap/agg/Segment.html#waitUntilLoaded()">

Segment.waitUntilLoaded()</a> is an example of this.</p>
<p>The following objects are cached.</p>
<!-- 
########################
##  1. Segment     #####
######################## -->
<h1>1. Segment<a name="#segment">&nbsp;</a></h1>
<p>A Segment (<a href="api/mondrian/rolap/agg/Segment.html">class
mondrian.rolap.agg.Segment</a>) is a collection of cell values parameterized by
a measure, and a set of (column, value) pairs. An example of a segment is</p>
<blockquote>
  <p>(Unit sales, Gender = 'F', State in {'CA','OR'}, Marital Status = <i>
  anything</i>)</p>

</blockquote>
<p>All segments over the same set of columns belong to an Aggregation, in this
case</p>
<blockquote>
  <p>('Sales' Star, Gender, State, Marital Status)</p>
</blockquote>
<p>Note that different measures (in the same Star) occupy the same Aggregation.
Aggregations belong to the AggregationManager, a singleton.</p>
<p>Segments are pinned during the evaluation of a single MDX query. The query
evaluates the expressions twice. The first pass, it finds which cell values it
needs, pins the segments containing the ones which are already present (one
pin-count for each cell value used), and builds a cell request (<a href="api/mondrian/rolap/CachePool.Cacheable.html">class
mondrian.rolap.agg.CellRequest</a>) for those which are not present. It executes
the cell request to bring the required cell values into the cache, again,
pinned. Then it evalutes the query a second time, knowing that all cell values
are available. Finally, it releases the pins.</p>
<!-- 
########################
##  2. Member set  #####
######################## -->
<h1>2. Member set<a name="memberset">&nbsp;</a></h1>

<p>A member set (<a href="api/mondrian/rolap/SmartMemberReaderChildrenList.html">class
mondrian.rolap.SmartMemberReader.ChildrenList</a>) is a set of children of a
particular member. It belongs to a member reader (<a href="api/mondrian/rolap/SmartMemberReader.html">class
mondrian.rolap.SmartMemberReader</a>).</p>
<!-- 
########################
##  3. Schema      #####
######################## -->
<h1>3. Schema<a name="schema">&nbsp;</a></h1>
<p>Schemas (<a href="api/mondrian/rolap/RolapSchema.html">class
mondrian.rolap.RolapSchema</a>) are cached in
<a href="api/mondrian/rolap/RolapStar.Pool.html">class
mondrian.rolap.RolapSchema.Pool</a>, which is a singleton (todo: use soft
references). The cache key is the URL which the schema was loaded from.</p>
<!-- 
#########################
##  4. Star schemas #####
######################### -->
<h1>4. Star schemas<a name="starSchemas">&nbsp;</a></h1>
<p>Star schemas (<a href="api/mondrian/rolap/RolapStar.html">class
mondrian.rolap.RolapStar</a>) are stored in the static member <code>
RolapStar.stars</code> (todo: use soft references), and accessed via <code>

RolapStar.getOrCreateStar(RolapSchema, MondrianDef.Relation)</code>.</p>
<br />
<br />

<hr noshade size="1"/>
<p>
    Author: Julian Hyde; last modified August 2006.<br/>
    Version: $Id$
    (<a href="http://p4web.eigenbase.org/open/mondrian/doc/components.html?ac=22">log</a>)<br/>
    Copyright (C) 2002-2005 Julian Hyde<br/>
    Copyright (C) 2005-2006 Pentaho
</p>

<br />

<!-- doc2web end -->

</body>
</html>
